doc: add detailed doc for enum descriptions. #825
Conversation
| } | ||
| ``` | ||
|
|
||
| ### Tips for Effective Enum Descriptions |
|
|
||
| When your argument or option uses an enum type, you can provide detailed descriptions for each enum value that will appear in the help screen. This is especially useful when the enum cases represent complex concepts that benefit from explanation. | ||
|
|
||
| ### Basic Enum Value Descriptions |
There was a problem hiding this comment.
can we use just one enum throughout this documentation, I think output format is a good example
|
ميه ميه اوكي
في السبت، ٤ أكتوبر ٢٠٢٥ ٧:٥٧ ص Rauhul Varma ***@***.***> كتب:
… ***@***.**** commented on this pull request.
------------------------------
In Sources/ArgumentParser/Documentation.docc/Articles/CustomizingHelp.md
<#825 (comment)>
:
> @@ -150,6 +150,150 @@ OPTIONS:
For an ``ExpressibleByArgument`` and `CaseIterable` type with many cases, you may still want to implement ``ExpressibleByArgument/allValueStrings`` to avoid an overly long list of values appearing in the help screen. For these types it is recommended to include the most common possible values.
+## Providing Descriptions for Individual Enum Values
+
+When your argument or option uses an enum type, you can provide detailed descriptions for each enum value that will appear in the help screen. This is especially useful when the enum cases represent complex concepts that benefit from explanation.
+
+### Basic Enum Value Descriptions
can we use just one enum throughout this documentation, I think output
format is a good example
—
Reply to this email directly, view it on GitHub
<#825 (review)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/BYB4MMVHG5KRUXLOLUY6JGT3V5HR3AVCNFSM6AAAAACIIHOZMSVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTGMBRGU3TQMRXHE>
.
You are receiving this because you are subscribed to this thread.Message
ID: ***@***.***>
|
|
Implemented feedback, lmk what else I can do! |
|
Haha, thanks! هاي
في السبت، ٤ أكتوبر ٢٠٢٥ ١١:٠٠ م Louis Qian ***@***.***> كتب:
… *louisunlimited* left a comment (apple/swift-argument-parser#825)
<#825 (comment)>
Implemented feedback, lmk what else I can do!
—
Reply to this email directly, view it on GitHub
<#825 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/BYB4MMTGFPRDYFBG5YN576L3WARO7AVCNFSM6AAAAACIIHOZMSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTGNRYGUYDOMJSGY>
.
You are receiving this because you commented.Message ID:
***@***.***>
|
There was a problem hiding this comment.
Thanks for working on the documentation, @louisunlimited! I've requested some changes below.
| ### Customizing Help for Arguments | ||
|
|
||
| For more control over the help text, pass an ``ArgumentHelp`` instance instead of a string literal. The `ArgumentHelp` type can include an abstract (which is what the string literal becomes), a discussion, a value name to use in the usage string, and a visibility level for that argument. | ||
| For more control over the help text, pass an `ArgumentHelp` instance instead of a string literal. The `ArgumentHelp` type can include an abstract (which is what the string literal becomes), a discussion, a value name to use in the usage string, and a visibility level for that argument. |
There was a problem hiding this comment.
These changes are removing links to the documentation (the double backticks) – can you revert that?
| ### Working with Raw Values | ||
|
|
||
| For enums with custom raw values, the descriptions work with the raw value representation. Here's the same `OutputFormat` enum with custom raw values: | ||
|
|
||
| ```swift | ||
| enum OutputFormat: String, CaseIterable, ExpressibleByArgument { | ||
| case json = "json" | ||
| case yaml = "yml" | ||
| case xml = "xml" | ||
| case csv = "csv" | ||
|
|
||
| var defaultValueDescription: String { | ||
| switch self { | ||
| case .json: | ||
| return "JavaScript Object Notation format" | ||
| case .yaml: | ||
| return "YAML Ain't Markup Language format" | ||
| case .xml: | ||
| return "eXtensible Markup Language format" | ||
| case .csv: | ||
| return "Comma-Separated Values format" | ||
| } | ||
| } | ||
| } | ||
|
|
||
| struct DataExporter: ParsableCommand { | ||
| @Option(help: "Select output format") | ||
| var format: OutputFormat = .json | ||
| } | ||
| ``` | ||
|
|
||
| In this example, users would specify `--format yml` to get YAML output, but the help screen still shows the descriptive text. |
There was a problem hiding this comment.
The content in this section is covered above, under the "Deriving Possible Values" header. Could you look at improving that section if it doesn't cover what you'd like to see?
There was a problem hiding this comment.
Yeah I think you're right, I was trying to cover all the cases and make this section be a no brainer read through. It can be removed.
| -h, --help Show help information. | ||
| ``` | ||
|
|
||
| ### Array Options with Enum Descriptions |
There was a problem hiding this comment.
I don't think this section needs to exist, since the customization / help screen display is the same whether a type is included a single option or as an array. The first sentence ("The same enum value descriptions...") could be included after the last example, if you'd like.
There was a problem hiding this comment.
Yeah, I'll nuke this section.
| ## Providing Descriptions for Individual Enum Values | ||
|
|
||
| When your argument or option uses an enum type, you can provide detailed descriptions for each enum value that will appear in the help screen. This is especially useful when the enum cases represent complex concepts that benefit from explanation. | ||
|
|
||
| ### Basic Enum Value Descriptions |
There was a problem hiding this comment.
Since the other two sub-sections here will be eliminated, can you just use a single header for this section about customizing the value descriptions? This should use a level 4 header (i.e. ####) since it's under the "Enumerating Possible Values" section.
|
@natecook1000 just did all the changes! Let me know what else you need :)) |
4 participants
Adds some doc on usage with adding enum help texts. I also asked claude to add some helpful tips in there, but can remove them if it's too much.
Checklist